<?php

namespace Kunfeng\Dify\Client;

use Kunfeng\Dify\Callback\ChatStreamCallback;
use Kunfeng\Dify\Model\Chat\ChatMessage;
use Kunfeng\Dify\Model\Chat\ChatMessageResponse;
use Kunfeng\Dify\Model\Chat\MessageListResponse;
use Kunfeng\Dify\Model\Chat\ConversationListResponse;
use Kunfeng\Dify\Model\Chat\Conversation;
use Kunfeng\Dify\Model\Chat\SuggestedQuestionsResponse;
use Kunfeng\Dify\Model\Chat\AudioToTextResponse;
use Kunfeng\Dify\Model\Chat\AnnotationListResponse;
use Kunfeng\Dify\Model\Chat\AnnotationReply;
use Kunfeng\Dify\Model\Chat\VariableResponse;
use Kunfeng\Dify\Model\Common\SimpleResponse;

/**
 * Dify 工作流编排对话型应用客户端接口
 */
interface DifyChatflowClientInterface extends DifyBaseClientInterface
{
    /**
     * 发送工作流编排对话消息（阻塞模式）
     */
    public function sendChatMessage(ChatMessage $message): ChatMessageResponse;

    /**
     * 发送工作流编排对话消息（流式模式）
     */
    public function sendChatMessageStream(ChatMessage $message, ChatStreamCallback $callback): void;

    /**
     * 获取消息列表
     */
    public function getMessages(string $conversationId, string $user, ?string $firstId = null, ?int $limit = null): MessageListResponse;

    /**
     * 获取会话列表
     */
    public function getConversations(string $user, ?string $firstId = null, ?int $limit = null, ?string $pinned = null): ConversationListResponse;

    /**
     * 重命名会话
     */
    public function renameConversation(string $conversationId, string $name, bool $autoGenerate = false, ?string $user = null): Conversation;

    /**
     * 删除会话
     */
    public function deleteConversation(string $conversationId, string $user): SimpleResponse;

    /**
     * 发送消息反馈
     */
    public function feedbackMessage(string $messageId, string $rating, string $user, ?string $comment = null): SimpleResponse;

    /**
     * 获取建议问题
     */
    public function getSuggestedQuestions(string $messageId, string $user): SuggestedQuestionsResponse;

    /**
     * 语音转文字
     */
    public function audioToText($file, string $user): AudioToTextResponse;

    /**
     * 文字转语音
     */
    public function textToAudio(?string $messageId = null, ?string $text = null, ?string $user = null): string;

    /**
     * 获取标注列表
     */
    public function getAnnotations(string $messageId, string $user): AnnotationListResponse;

    /**
     * 回复标注
     */
    public function replyAnnotation(string $messageId, string $annotationId, AnnotationReply $reply, string $user): SimpleResponse;

    /**
     * 获取应用变量
     */
    public function getAppVariables(): VariableResponse;
}
